<html>
<head><meta charset="utf-8"><title>docs based on macro input · general · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/index.html">general</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html">docs based on macro input</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="220038628"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220038628" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220038628">(Dec 15 2020 at 20:36)</a>:</h4>
<p>Is there any way to get docs that include a token from a <code>macro_rules!</code> input?</p>
<p>Essentially I want something like this:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="cp">#[doc = </span><span class="s">"See [`Diagnostic::"</span><span class="cp"> + stringify!($n) + </span><span class="s">"()`]."</span><span class="cp">]</span><span class="w"></span>
</code></pre></div>
<p>but that gives the syntax error:</p>
<div class="codehilite"><pre><span></span><code> error: expected `]`, found `+`
   --&gt; compiler/rustc_errors/src/diagnostic_builder.rs:79:38
    |
41  | / macro_rules! forward {
42  | |     // Forward pattern for &amp;self -&gt; &amp;Self
43  | |     (
44  | |         $(#[$attrs:meta])*
...   |
79  | |         #[doc = &quot;See [`Diagnostic::&quot; + stringify!($n) + &quot;()`].&quot;]
    | |                                      ^ expected `]`
...   |
84  | |     };
85  | | }
    | |_- in this expansion of `forward!`
</code></pre></div>
<p>I also tried:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="cp">#![doc = concat!(</span><span class="s">"See [`Diagnostic::"</span><span class="cp">, stringify!(foo), </span><span class="s">"()`]."</span><span class="cp">)]</span><span class="w"></span>
</code></pre></div>
<p>on the playground, but that gives:</p>
<div class="codehilite"><pre><span></span><code>error: unexpected token: `concat`
 --&gt; src/lib.rs:1:10
  |
1 | #![doc = concat!(&quot;See [`Diagnostic::&quot;, stringify!(foo), &quot;()`].&quot;)]
  |          ^^^^^^
</code></pre></div>



<a name="220038638"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220038638" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220038638">(Dec 15 2020 at 20:36)</a>:</h4>
<p>cc <a href="https://github.com/rust-lang/rust/issues/80046">#80046</a></p>



<a name="220040309"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220040309" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jonas Schievink  [he/him] <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220040309">(Dec 15 2020 at 20:49)</a>:</h4>
<p>Something like this should work:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="n">macro_rules</span><span class="o">!</span><span class="w"> </span><span class="n">m</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="p">(</span><span class="cp">$e</span>:<span class="nc">expr</span><span class="p">)</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="cp">#[doc = $e]</span><span class="w"></span>
<span class="w">        </span><span class="k">struct</span> <span class="nc">S</span><span class="p">;</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="n">m</span><span class="o">!</span><span class="p">(</span><span class="n">concat</span><span class="o">!</span><span class="p">(</span><span class="s">"See [`Diagnostic::"</span><span class="p">,</span><span class="w"> </span><span class="n">stringify</span><span class="o">!</span><span class="p">(</span><span class="n">foo</span><span class="p">),</span><span class="w"> </span><span class="s">"()`]."</span><span class="p">));</span><span class="w"></span>
</code></pre></div>



<a name="220041056"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220041056" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220041056">(Dec 15 2020 at 20:55)</a>:</h4>
<p>Hmm, so I have to create another macro inside my macro?</p>



<a name="220041242"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220041242" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220041242">(Dec 15 2020 at 20:56)</a>:</h4>
<p>Actually I don't think that will solve my problem.</p>



<a name="220041369"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220041369" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220041369">(Dec 15 2020 at 20:57)</a>:</h4>
<p>The macro I'm working with is from <code>compiler/rustc_errors</code>:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="n">macro_rules</span><span class="o">!</span><span class="w"> </span><span class="n">forward</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="c1">// Forward pattern for &amp;self -&gt; &amp;Self</span>
<span class="w">    </span><span class="p">(</span><span class="w"></span>
<span class="w">        </span><span class="cp">$(#[$attrs:meta]</span><span class="p">)</span><span class="o">*</span><span class="w"></span>
<span class="w">        </span><span class="k">pub</span><span class="w"> </span><span class="k">fn</span> <span class="cp">$n</span>:<span class="nc">ident</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">,</span><span class="w"> </span><span class="cp">$($name</span>:<span class="nc">ident</span>: <span class="cp">$ty</span>:<span class="nc">ty</span><span class="p">),</span><span class="o">*</span><span class="w"> </span><span class="cp">$(,</span><span class="p">)</span><span class="o">?</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="kp">&amp;</span><span class="nc">Self</span><span class="w"></span>
<span class="w">    </span><span class="p">)</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="cp">$(#[$attrs]</span><span class="p">)</span><span class="o">*</span><span class="w"></span>
<span class="w">        </span><span class="cp">#[doc = </span><span class="s">"See [`Diagnostic::"</span><span class="cp"> + stringify!($n) + </span><span class="s">"()`]."</span><span class="cp">]</span><span class="w"></span>
<span class="w">        </span><span class="k">pub</span><span class="w"> </span><span class="k">fn</span> <span class="cp">$n</span><span class="p">(</span><span class="o">&amp;</span><span class="bp">self</span><span class="p">,</span><span class="w"> </span><span class="cp">$($name</span>: <span class="cp">$ty</span><span class="p">),</span><span class="o">*</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="kp">&amp;</span><span class="nc">Self</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="bp">self</span><span class="p">.</span><span class="n">diagnostic</span><span class="p">.</span><span class="cp">$n</span><span class="p">(</span><span class="cp">$($name</span><span class="p">),</span><span class="o">*</span><span class="p">);</span><span class="w"></span>
<span class="w">            </span><span class="bp">self</span><span class="w"></span>
<span class="w">        </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span><span class="p">};</span><span class="w"></span>

<span class="w">    </span><span class="c1">// Forward pattern for &amp;mut self -&gt; &amp;mut Self</span>
<span class="w">    </span><span class="p">(</span><span class="w"></span>
<span class="w">        </span><span class="cp">$(#[$attrs:meta]</span><span class="p">)</span><span class="o">*</span><span class="w"></span>
<span class="w">        </span><span class="k">pub</span><span class="w"> </span><span class="k">fn</span> <span class="cp">$n</span>:<span class="nc">ident</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="bp">self</span><span class="p">,</span><span class="w"> </span><span class="cp">$($name</span>:<span class="nc">ident</span>: <span class="cp">$ty</span>:<span class="nc">ty</span><span class="p">),</span><span class="o">*</span><span class="w"> </span><span class="cp">$(,</span><span class="p">)</span><span class="o">?</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="kp">&amp;</span><span class="nc">mut</span><span class="w"> </span><span class="bp">Self</span><span class="w"></span>
<span class="w">    </span><span class="p">)</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="cp">$(#[$attrs]</span><span class="p">)</span><span class="o">*</span><span class="w"></span>
<span class="w">        </span><span class="cp">#[doc = </span><span class="s">"See [`Diagnostic::"</span><span class="cp"> + stringify!($n) + </span><span class="s">"()`]."</span><span class="cp">]</span><span class="w"></span>
<span class="w">        </span><span class="k">pub</span><span class="w"> </span><span class="k">fn</span> <span class="cp">$n</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="bp">self</span><span class="p">,</span><span class="w"> </span><span class="cp">$($name</span>: <span class="cp">$ty</span><span class="p">),</span><span class="o">*</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="kp">&amp;</span><span class="nc">mut</span><span class="w"> </span><span class="bp">Self</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="bp">self</span><span class="p">.</span><span class="mf">0.</span><span class="n">diagnostic</span><span class="p">.</span><span class="cp">$n</span><span class="p">(</span><span class="cp">$($name</span><span class="p">),</span><span class="o">*</span><span class="p">);</span><span class="w"></span>
<span class="w">            </span><span class="bp">self</span><span class="w"></span>
<span class="w">        </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span><span class="p">};</span><span class="w"></span>

<span class="w">    </span><span class="c1">// Forward pattern for &amp;mut self -&gt; &amp;mut Self, with S: Into&lt;MultiSpan&gt;</span>
<span class="w">    </span><span class="c1">// type parameter. No obvious way to make this more generic.</span>
<span class="w">    </span><span class="p">(</span><span class="w"></span>
<span class="w">        </span><span class="cp">$(#[$attrs:meta]</span><span class="p">)</span><span class="o">*</span><span class="w"></span>
<span class="w">        </span><span class="k">pub</span><span class="w"> </span><span class="k">fn</span> <span class="cp">$n</span>:<span class="nc">ident</span><span class="o">&lt;</span><span class="n">S</span>: <span class="nb">Into</span><span class="o">&lt;</span><span class="n">MultiSpan</span><span class="o">&gt;&gt;</span><span class="p">(</span><span class="w"></span>
<span class="w">            </span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="bp">self</span><span class="p">,</span><span class="w"></span>
<span class="w">            </span><span class="cp">$($name</span>:<span class="nc">ident</span>: <span class="cp">$ty</span>:<span class="nc">ty</span><span class="p">),</span><span class="o">*</span><span class="w"></span>
<span class="w">            </span><span class="cp">$(,</span><span class="p">)</span><span class="o">?</span><span class="w"></span>
<span class="w">        </span><span class="p">)</span><span class="w"> </span>-&gt; <span class="kp">&amp;</span><span class="nc">mut</span><span class="w"> </span><span class="bp">Self</span><span class="w"></span>
<span class="w">    </span><span class="p">)</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="cp">$(#[$attrs]</span><span class="p">)</span><span class="o">*</span><span class="w"></span>
<span class="w">        </span><span class="cp">#[doc = </span><span class="s">"See [`Diagnostic::"</span><span class="cp"> + stringify!($n) + </span><span class="s">"()`]."</span><span class="cp">]</span><span class="w"></span>
<span class="w">        </span><span class="k">pub</span><span class="w"> </span><span class="k">fn</span> <span class="cp">$n</span><span class="o">&lt;</span><span class="n">S</span>: <span class="nb">Into</span><span class="o">&lt;</span><span class="n">MultiSpan</span><span class="o">&gt;&gt;</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span><span class="w"> </span><span class="bp">self</span><span class="p">,</span><span class="w"> </span><span class="cp">$($name</span>: <span class="cp">$ty</span><span class="p">),</span><span class="o">*</span><span class="p">)</span><span class="w"> </span>-&gt; <span class="kp">&amp;</span><span class="nc">mut</span><span class="w"> </span><span class="bp">Self</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="bp">self</span><span class="p">.</span><span class="mf">0.</span><span class="n">diagnostic</span><span class="p">.</span><span class="cp">$n</span><span class="p">(</span><span class="cp">$($name</span><span class="p">),</span><span class="o">*</span><span class="p">);</span><span class="w"></span>
<span class="w">            </span><span class="bp">self</span><span class="w"></span>
<span class="w">        </span><span class="p">}</span><span class="w"></span>
<span class="w">    </span><span class="p">};</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>



<a name="220041435"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220041435" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220041435">(Dec 15 2020 at 20:58)</a>:</h4>
<p>And I want it to automatically add that documentation based on the function name. Is there no way to do it automatically?</p>



<a name="220041999"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220041999" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Jonas Schievink  [he/him] <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220041999">(Dec 15 2020 at 21:03)</a>:</h4>
<p>You can't pass it through this?</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="n">macro_rules</span><span class="o">!</span><span class="w"> </span><span class="n">m</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="p">(</span><span class="cp">$e</span>:<span class="nc">expr</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="cp">$i</span>:<span class="nc">item</span><span class="p">)</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="cp">#[doc = $e]</span><span class="w"></span>
<span class="w">        </span><span class="cp">$i</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>



<a name="220042221"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220042221" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220042221">(Dec 15 2020 at 21:04)</a>:</h4>
<p>Hmm, maybe that <em>will</em> work! I'll try it and let you know.</p>



<a name="220046032"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220046032" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lukas Wirth <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220046032">(Dec 15 2020 at 21:35)</a>:</h4>
<p>(deleted)</p>



<a name="220047878"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220047878" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220047878">(Dec 15 2020 at 21:52)</a>:</h4>
<p>I tried it, and rustdoc succeeded, but the docs didn't show up in the output.</p>



<a name="220048007"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220048007" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220048007">(Dec 15 2020 at 21:53)</a>:</h4>
<p>Actually those docs might have been stale...</p>



<a name="220051691"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220051691" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220051691">(Dec 15 2020 at 22:24)</a>:</h4>
<blockquote>
<p>#![doc = concat!("See [<code>Diagnostic::", stringify!(foo), "()</code>].")]</p>
</blockquote>
<p><span class="user-mention" data-user-id="307537">@Camelid</span> I would expect that to work unchanged on the next beta bump: <a href="https://github.com/rust-lang/rust/issues/78835">https://github.com/rust-lang/rust/issues/78835</a></p>



<a name="220051716"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220051716" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220051716">(Dec 15 2020 at 22:24)</a>:</h4>
<p>try on nightly instead of beta?</p>



<a name="220053427"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/122651-general/topic/docs%20based%20on%20macro%20input/near/220053427" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Noah Lev <a href="https://rust-lang.github.io/zulip_archive/stream/122651-general/topic/docs.20based.20on.20macro.20input.html#220053427">(Dec 15 2020 at 22:38)</a>:</h4>
<p>This is for compiler docs and it failed on CI so I guess it'll have to wait for the beta bump. For now I'm using <span class="user-mention silent" data-user-id="211727">Jonas Schievink</span>'s macro hack to make it work.</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>